Add custom error handling for non-git repositories with initialization option #10483

Copilot · 2025-09-28T18:16:16Z

When users attempt to set a non-git directory as an active project, GitButler now provides a user-friendly experience with an option to initialize a git repository directly from the error dialog.

Problem

Previously, when users tried to open a project in a directory that wasn't a git repository, they would encounter a generic error message with no clear path forward. This created friction in the onboarding experience and left users unsure how to proceed.

Solution

This PR implements a complete solution that:

Detects non-git repositories - Enhanced set_project_active() to recognize when git2::Repository::open() fails due to missing git structure (error codes: NotFound, Invalid, Config)
Provides custom error classification - Added new NonGitRepository error code to the error system that maps from backend to frontend
Offers guided remediation - Shows a special warning toast with an "Initialize Repository" button instead of a generic error
Safely initializes git repositories - New init_git_repository() Tauri command with comprehensive safety checks:
- Validates directory exists and is writable
- Prevents overwriting existing git repositories
- Includes proper error handling and logging
Seamless user experience - After successful initialization, automatically retries loading the project

User Flow

User opens non-git directory
     ↓
GitButler detects missing .git structure
     ↓
Warning toast: "Not a Git repository - Would you like to initialize one?"
     ↓
User clicks "Initialize Repository"
     ↓
Git repo created safely with validation
     ↓
Success message + automatic project loading

Technical Implementation

Backend Changes:

Added NonGitRepository variant to gitbutler_error::error::Code
Enhanced error detection in set_project_active() with multiple git2 error code mapping
New init_git_repository() command with write permission validation
Comprehensive error handling for edge cases

Frontend Changes:

Added error code mapping in knownErrors.ts
Enhanced project layout error handling to detect specific error code
Interactive toast with action button for git initialization
Service method integration for backend communication

Safety & Validation

Path validation: Ensures target is an existing, writable directory
Existing repository protection: Prevents initialization in directories that are already git repositories
Permission checks: Validates write access before attempting initialization
Error boundaries: Comprehensive error handling for all failure modes

This change maintains full backward compatibility while significantly improving the user experience for a common onboarding scenario. Users can now seamlessly convert any directory into a GitButler-compatible project with a single click.

Original prompt

When setting the active project to a non-git repository, attache a custom Code to the error. That error is recogoniced when adding the project, and a popup displays that offers the user to initialise a repository at that directory, before retrying.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

vercel · 2025-09-28T18:16:22Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
gitbutler-web	Ignored	Preview		Sep 30, 2025 0:21am

Byron

I processed the PR to be usable, but it needs frontend work.

The basis already works and isn't bad at all.

Screen.Recording.2025-09-29.at.06.02.53.mov

But to truly work, it needs some finesse that I unfortunately cannot provide.
Maybe a low-hanging fruit to pick if it's not too complicated to actually do.

CC @PavelLaptev and @estib-vega

PS: the PR is based on this message on Discord.

Byron · 2025-09-29T04:01:33Z

crates/gitbutler-tauri/src/projects.rs

+#[tauri::command]
+#[instrument(err(Debug))]
+pub fn init_git_repository(path: String) -> Result<(), Error> {


This function trivially would have to be moved to but-api.

Byron · 2025-09-29T04:02:05Z

apps/desktop/src/lib/project/project.ts

+				message:
+					'The selected directory is not a Git repository. Would you like to initialize one?',
+				style: 'warning',
+				extraAction: {
+					label: 'Initialize Repository',
+					onClick: async (dismiss) => {
+						try {


Here is the main difficulty: initialising and re-adding the project from here to get a project id.

Let me take a look!

estib-vega · 2025-09-29T08:29:46Z

@Byron, just to clarify:

That warning pop-up is shown when the backend hits: https://github.com/gitbutlerapp/gitbutler/blob/master/crates/gitbutler-project/src/controller.rs#L100

My understanding is that this is a catch-all response for failing to open a directory. So, just wanted to confirm that that can only mean that the repository is not initialized. Otherwise, we'd be offering a 'false' fix action.

Byron · 2025-09-29T09:24:31Z

My understanding is that this is a catch-all response for failing to open a directory. So, just wanted to confirm that that can only mean that the repository is not initialized. Otherwise, we'd be offering a 'false' fix action.

That's a very good point - right now it's very 'rough'.

Can I add this improvement as second pass on yours?
One would have to match on gix::open to fail in a particular way, and associate this with a unique enum variant to trigger the "not initialised" popup only when nothing else went wrong.

❯ gix free discover
open (strict) .:
        "." does not appear to be a git repository

        Caused by:
            Missing HEAD at '.git/HEAD'
open (lenient) .:
        "." does not appear to be a git repository

        Caused by:
            Missing HEAD at '.git/HEAD'

discover from .:
        Could not find a git repository in '.' or in any of its parents

discover (plumbing) from .:
        Could not find a git repository in '.' or in any of its parents

Error: At least one operation failed

…oject Co-authored-by: Byron <[email protected]>

…it directory

Move the method for initializing a repository by its path to the shared API module, so that the server can have this as well

When adding a non-git repostory and then chossing to initialize that, the application should correcly add the project

estib-vega · 2025-09-30T12:00:13Z

@Byron This effort might need more planning that probably intended. Let me know what you think:

The option to initialize a directory as a git repository will lead for the project to be added, but the next thing that the user will see is an error page:

The issue is that no project without a remote can be added to the application (yet) and so it explodes

estib-vega · 2025-09-30T12:04:35Z

We might want to add more methods to address this gracefully, from the application, but that seems to increase the scope of this as bit too much.

At this point, we need to design this flow correctly (because this state can already be encountered regardless of whether this changes make it into the application)

I'll tag here @PavelLaptev, since we need to make some time to work this flow (IMO we can get away with just displaying a splash screen asking the user to add a remote to their repository from the terminal and pushing).

estib-vega · 2025-09-30T12:06:21Z

In its current state, I'll avoid merging this, since we'd be adding a big pathway into scary cul-de-sac

Byron · 2025-09-30T12:07:29Z

I see 😅.

I'd say we salvage what's there, I improve the error handling so it's precise, and we merge it as is knowing that soon this will be covered by single-branch mode.

Probably once we have improved onboarding to not enforce setting the target branch anyway, we'd want to have an E2E test for this extended flow:

as a new user with onboarding completed
add non-git directory
initialise it here
see the newly initialised repo in single-branch mode

Wonderful :).

Also definitely CC @krlvi and @mtsgrd just to be sure this goes in the right direction.

estib-vega · 2025-09-30T12:09:45Z

see the newly initialised repo in single-branch mode

I'd wait for this to be implemented before merging this, though.

I wouldn't like to trade a warning pop-up for a non-actionable full-screen error

Byron · 2025-09-30T12:12:32Z

Alright - I got carried away. I will add the error selection now and you can take it over again.

… false positives.

Byron · 2025-09-30T12:21:47Z

Here is the commit - and now that I tried it myself I totally understand why we should not just merge this.
The experience isn't very satisfying just now.

Screen.Recording.2025-09-30.at.14.20.06.mov

PavelLaptev · 2025-09-30T14:03:00Z

Thanks @estib-vega Ill check this out

Copilot AI assigned Copilot and Byron Sep 28, 2025

Copilot started work on behalf of Byron September 28, 2025 18:16 View session

vercel bot temporarily deployed to Preview September 28, 2025 18:16 Inactive

Copilot AI requested a review from Byron September 28, 2025 18:46

Copilot finished work on behalf of Byron September 28, 2025 18:46

github-actions bot added rust Pull requests that update Rust code @gitbutler/desktop labels Sep 29, 2025

Byron force-pushed the copilot/fix-39e85eac-2ac8-479c-9252-27cba9b10ed2 branch from 3af024b to cd0e2c1 Compare September 29, 2025 04:01

Byron reviewed Sep 29, 2025

View reviewed changes

Byron added the UX/UI Focusing on user satisfaction, usability, and overall experience label Sep 29, 2025

Byron requested a review from estib-vega September 29, 2025 04:06

estib-vega force-pushed the copilot/fix-39e85eac-2ac8-479c-9252-27cba9b10ed2 branch from cd0e2c1 to a860421 Compare September 29, 2025 10:34

Copilot AI and others added 5 commits September 30, 2025 13:43

Offer to initialise a repository when adding a simple directory as pr…

46a8f31

…oject Co-authored-by: Byron <[email protected]>

refactor

256b2c8

Handle correctly the initialization of a repository on adding a non-g…

92478b7

…it directory

Move the repo initialization to the API

a0621e2

Move the method for initializing a repository by its path to the shared API module, so that the server can have this as well

Instrument and update the E2E test for adding a non-git repostory

c15f679

When adding a non-git repostory and then chossing to initialize that, the application should correcly add the project

estib-vega force-pushed the copilot/fix-39e85eac-2ac8-479c-9252-27cba9b10ed2 branch from a860421 to c15f679 Compare September 30, 2025 11:57

github-actions bot added the @gitbutler/ui label Sep 30, 2025

Respond to the right error when opening a non-git repository to avoid…

f36d7bd

… false positives.

kmk142789 approved these changes Oct 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add custom error handling for non-git repositories with initialization option #10483

Add custom error handling for non-git repositories with initialization option #10483

Uh oh!

Copilot AI commented Sep 28, 2025 •

edited

Loading

Uh oh!

vercel bot commented Sep 28, 2025 •

edited

Loading

Uh oh!

Byron left a comment •

edited

Loading

Uh oh!

Byron Sep 29, 2025

Uh oh!

Byron Sep 29, 2025

Uh oh!

estib-vega Sep 29, 2025

Uh oh!

estib-vega commented Sep 29, 2025

Uh oh!

Byron commented Sep 29, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

PavelLaptev commented Sep 30, 2025

Uh oh!

Uh oh!

Add custom error handling for non-git repositories with initialization option #10483

Are you sure you want to change the base?

Add custom error handling for non-git repositories with initialization option #10483

Uh oh!

Conversation

Copilot AI commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

User Flow

Technical Implementation

Safety & Validation

Uh oh!

vercel bot commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Byron left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Byron Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

Byron Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

estib-vega Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

estib-vega commented Sep 29, 2025

Uh oh!

Byron commented Sep 29, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

estib-vega commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

Byron commented Sep 30, 2025

Uh oh!

PavelLaptev commented Sep 30, 2025

Uh oh!

Uh oh!

Copilot AI commented Sep 28, 2025 •

edited

Loading

vercel bot commented Sep 28, 2025 •

edited

Loading

Byron left a comment •

edited

Loading